test(uds): drive functional response windows from an injected clock - #183

What does this change?

Functional UDS windows and J1939-TP deadlines were armed on the wall clock, so a slow runner could push a frame across a window the test thought it was still inside. That is the macOS failure of A_Late_Negative_Answer_To_A_Suppressed_Send_Does_Not_Land_In_The_Next_Window (run 36234735257, ContainSingle).

J1939TpChannel now takes an optional ProtocolActor, the same way the J1939 node does. It owns that actor only when it created one. J1939Tp.Open is unchanged, and a node still does not hand its own actor to a TP channel it opens internally.

Functional ISO-TP collection and UdsFunctionalClient take the same optional actor. Null keeps CancelAfter and Stopwatch. A test that passes an actor also stamps host arrival and handoff from that actor's clock, through an internal CanBusService overload, so a deadline and a frame stamp stay comparable.

Refs #171. First slice only. Whether the rest of #171 is a hardening track or release-blocking is the issue's open decision question; this pull request does not close it.

Injection shape

• internal J1939TpChannel(..., ProtocolActor? actor = null). No separate ITimeSource parameter: timers read the actor's clock, as J1939NodeImpl does. Production default is still new ProtocolActor().
• J1939TpChannel.Dispose never disposes a borrowed actor. The maintainer chose to harden this path here rather than align it with IsoTpChannel / J1939NodeImpl.
  • It first joins the reader and closes the subscription.
  • From then on, HandleIncoming drops any frame the actor reaches, whenever it gets to it. A reader that outlives its join therefore cannot open a session behind the cleanup.
  • With an owned actor, disposing the actor runs the cleanup.
  • With a borrowed actor, it posts the cleanup and waits up to 2 s. If the cleanup runs in time, every in-flight and queued send has failed when Dispose returns.
  • If the borrowed actor is still busy after 2 s, Dispose reports a TimeoutException on BackgroundExceptionOccurred and returns. An owned service is disposed only after the cleanup has run.
  • On the actor's own loop, where waiting would deadlock, it fails the sessions inline.
  • If the borrowed actor is already disposed, it leaves that actor's sessions alone.
• internal IsoTpFunctionalClient(..., ProtocolActor? clock = null) and the listener it opens. IsoTp.OpenFunctional is unchanged.
• internal UdsFunctionalClient.Create(client, ProtocolActor? clock, ...). The public Create delegates to it with a null clock, so the P2 / P2* defaults are in one place.
• internal CanBusService(ICanBus bus, Func<long>? hostTimestamp). RawCan does not reference the actor assembly. The public constructor is unchanged.
• FunctionalWindow ends a collection window. On an injected actor, its timer callback (End) and its Dispose take one lock. A callback the loop picked up before the timer was cancelled finds the window disposed and does nothing. Disposal does not go through the actor, so an actor that is already torn down makes no difference.
• UdsFunctionalClient.DelayListenerStart(TimeSpan) is the test hook that was the ListenerStartDelay property. It throws on a client that has no injected clock, because on the wall clock it would be a sleep.

Tests moved onto the clock

In UdsFunctionalClientTests: the late-negative flake and the other functional-window cases that place a frame inside or past P2 / P2* (A_Late_Negative_Answer_To_A_Previous_Request_Does_Not_Land_In_The_Next_Window, A_Cancelled_Collection_Still_Leaves_Its_Window_For_The_Next_Call, A_Pending_Answer_Collected_After_P2_Does_Not_Revive_The_Window, A_Listener_Starting_After_The_Window_Still_Hears_What_It_Buffered, A_Cancelled_Collection_Does_Not_Lose_The_Pending_Answer_The_Listener_Heard, A_Cancelled_Wait_Leaves_The_Listener_To_Hear_The_Pending_Answer, A_Pending_Answer_In_The_Gap_After_A_Suppressed_Send_Is_Observed, A_Collection_That_Outlasts_The_Window_Does_Not_Leave_A_Zombie_Listener).

Bam_Packet_Spacing_Follows_The_Injected_Actors_Clock checks that wall time does not release the next TP.DT while the injected clock is frozen, and that advancing it does. A failed construction disposes an actor the channel created and leaves an injected one running.

New tests for the seam's own branches

Each was checked by breaking its line in the source and watching it fail.

• Functional_Collect_On_An_Injected_Clock_Drains_By_That_Clocks_Deadline: the drain after the window ends keeps a frame stamped at the deadline and drops one a tick later, plus an unstamped one.
• An_Unstamped_Functional_Response_Is_Stamped_From_The_Collectors_Clock.
• A_Clocked_Window_Ends_On_Its_Clock_And_Outlives_Its_Actor: the window ends when its clock says so; disposing it after its actor, then running a late callback, throws nothing.
• A_Suppressed_Send_Cancelled_After_The_Driver_Took_It_Leaves_P2_From_The_Cancellation.
• A_Suppressed_Send_Without_A_Transmit_Stamp_Is_Anchored_At_Its_Confirmation.
• A_Listener_Start_Delay_Needs_An_Injected_Clock.
• The borrowed-actor dispose paths, each with an in-flight BAM and a BAM queued behind it: Disposing_On_A_Busy_Borrowed_Actor_Fails_The_Send_Before_It_Returns, Disposing_On_A_Borrowed_Actor_Stuck_Past_The_Budget_Defers_The_Service, Disposing_From_The_Borrowed_Actors_Loop_Fails_The_Send_At_Once, Disposing_After_The_Borrowed_Actor_Leaves_Its_Sessions_To_It.
• Frames_The_Actor_Reaches_After_Dispose_Began_Are_Dropped: a complete BAM that the reader has already handed to a busy borrowed actor is not delivered once Dispose has begun.

What stays for follow-up

• Every other category-2 row in docs/reviews/2026-09-25-delay-sleep-audit.md: J1939 node backoff, the remaining J1939-TP timer sleeps (the seam is in place; those tests are not converted), ISO-TP, CANopen, raw CAN, and the physical UDS client's P2 rows in UdsClientTests.
• In UdsFunctionalClientTests, the sleeps that are not that window: the queue delay in A_Call_Queued_Behind_Another_Does_Not_Send_After_Dispose, the bus-pump delay in An_Invalid_Collection_Window_Transmits_Nothing, and the driver holds in the acceptance-anchor tests (Task.Delay(200), Task.Delay(2000), Task.Delay(1100), and the 150 ms negative that rides that hold). Those holds are a wall-clock gap across a stuck driver. Freezing the protocol clock would erase what they measure.
• The 50 ms lock-setup delay in A_Pending_Answer_From_Before_The_Handoff_Is_Not_This_Requests.

Type of change

• docs / test / refactor / chore / ci — no release

Every commit is refactor(...) or test(...), apart from the CodeQL autofix commit. That one has no Conventional Commit type, so the release analyser ignores it. None of the commits is a feat or a fix, so this pull request does not publish a release.

Checklist

• dotnet build CanKit.Pro.sln -c Release -p:CI=true succeeds
• dotnet test CanKit.Pro.sln -c Release --framework net10.0 passes
• dotnet format --verify-no-changes and dotnet pack + eng/verify-packages.py pass
• Public API unchanged; the new parameters are internal and commented
• New behaviour is covered by a test
• Refs Replace wall-clock category-2 test sleeps (macOS flake risk) #171

🤖 Generated with Claude Code

https://claude.ai/code/session_013WJ8h1ahw4Nj5dYuEWy34s